The API method to change the caption on the titlebar of a window is different for different window types. The two methods are explained below.

Liberty BASIC has a "titlebar" command that allows us to change the caption on the mainwindow.

titlebar "I'm a NEW Caption!"
wait

---

Windows of type "Window" and "Dialog

There is no command that changes the caption on GUI windows. We can do this very easily with an API call, SetWindowTextA. The function requires the handle to the window, which we retrieve with the HWND() function. It also requires a string or string variable containing the desired new caption. The return is nonzero if the function succeeds, and zero if it fails. Here is the function:

hWin=hwnd(#1)       'get window handle for API call

calldll #user32, "SetWindowTextA",_
hWin as ulong,_     'window handle
caption$ as ptr,_   'new caption
result as boolean   'nonzero = success

The code above is split into components with the underscore line continuation character so that each argument can be documented. API functions are actually contained on a single line of code. You can write it this way, if you'd like:

calldll #user32, "SetWindowTextA",hWin as ulong,caption$ as ptr,result as boolean   

That makes one simple line of code to change the caption of a window. Pretty easy, eh? Unfortunately, it won't work on windows of type "graphics" or "text".

---

Windows of type "Graphics" and "Text"

When we use the HWND() function to retrieve the handles of windows that are type "graphics" or type "text" we actually retrieve the handle of the graphicbox or texteditor PART of the window. If we try SetWindowTextA using this window handle, we won't be successful in changing the caption! We first need to get the handle of the parent window that contains the graphicbox or texteditor. That can be done very easily with the GetParent API call. It simply takes in the handle of the graphics window or text window that is retrieved with the HWND() function and it returns the parent window handle:

hChild=hwnd(#2)

calldll #user32, "GetParent",_
hChild as ulong,_   'handle of graphics
hParent as ulong    'returns handle of graphics parent

Once we have the parent handle, we can use that in the call to SetWindowTextA and change the caption of the window:

calldll #user32, "SetWindowTextA",_
hParent as ulong,_  'window handle
caption$ as ptr,_   'new caption
result as boolean   'nonzero = success

Each of these functions can be written on a single line, like this:

calldll #user32, "GetParent",hChild as ulong,hParent as ulong    
calldll #user32, "SetWindowTextA",hParent as ulong,caption$ as ptr,result as boolean

Here is a small demonstration program that shows how to change the caption on a plain window and on a graphics window.

---

DEMO

nomainwin
caption$="New Caption!"
WindowWidth=250:WindowHeight=200
UpperLeftY=10

UpperLeftX=10
button #1.b, "Change Caption",[changeOne],UL,10,10
Open "Plain Window" for window as #1
#1 "trapclose [quit]"

UpperLeftX=300
button #2.b, "Change Caption",[changeTwo],UL,10,10
Open "Graphics Window" for graphics_nsb as #2
#2 "trapclose [quit]"

wait

[quit] close #1:close #2:end

[changeOne]
hWin=hwnd(#1)
calldll #user32, "SetWindowTextA",_
hWin as ulong,_     'window handle
caption$ as ptr,_   'new caption
result as boolean   'nonzero = success
wait

[changeTwo]
hChild=hwnd(#2)

calldll #user32, "GetParent",_
hChild as ulong,_   'handle of graphics
hParent as ulong    'returns handle of graphics parent

calldll #user32, "SetWindowTextA",_
hParent as ulong,_  'window handle
caption$ as ptr,_   'new caption
result as boolean   'nonzero = success
wait

---